feat: improve --help output for AI agents and humans#1080
Merged
patrikbraborec merged 10 commits intomasterfrom Apr 20, 2026
Merged
feat: improve --help output for AI agents and humans#1080patrikbraborec merged 10 commits intomasterfrom
patrikbraborec merged 10 commits intomasterfrom
Conversation
Extends the command framework with examples, docsUrl, interactive, and group metadata, reworks the main help menu with category groups, and adds EXAMPLES + LEARN MORE sections modeled after gh. Also fixes misleading namespace descriptions, clarifies the 'actor' entrypoint's relationship to 'apify actor', supports 'help' as a positional arg equivalent to --help, and normalizes sentence punctuation across all descriptions. Refs #1060 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
patrikbraborec
added
t-dx
Per-command EXAMPLES and the main help menu now prefix example descriptions with "# " (shell-comment style), matching the `gh` CLI convention. Each example becomes a self-contained copy-paste block, which prevents AI agents from mistaking description prose for part of the command. Also updates the main-help `apify create` example to its interactive form (dropping the stray `my-actor` positional) with a comment explaining the flow, so users don't copy an invocation that looks incomplete. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
Author
|
@TC-MO I added you as optional review, if you want to check the help commands. |
Contributor
|
Thank you will check in the afternoon |
l2ysho
requested changes
Apr 15, 2026
Contributor
l2ysho
left a comment
l2ysho
left a comment
There was a problem hiding this comment.
thx @patrikbraborec, i found one possible problem, pls take a look
The previous help-rewrite logic scanned every positional past index 0 for the literal word "help", which hijacked commands whose own args happened to be "help" (e.g. `actor set-value key1 help` or `actor set-value help value1` would show help instead of writing to the key-value store). Only treat a positional as a help trigger when it is an actual subcommand slot: position 1 when the base command has subcommands, and position 2 only when position 1 is a real subcommand and that subcommand takes no positional args of its own. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Implements the findings from the staff review of the help output rework: prefix bare 'actor' example commands with the current entrypoint so they stay copy-pasteable when viewed under 'apify actor', render the interactive note on namespace commands, drop the now-unused mapGroupBy helper, add unit tests for the help renderers, and note the no-op path of the help-positional rewrite under the actor entrypoint. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
vladfrangu
requested changes
Apr 16, 2026
Member
vladfrangu
left a comment
vladfrangu
left a comment
There was a problem hiding this comment.
Can we get some before and after screenshots please 🙏
Clarify that 'apify login' prompts for a method before completing the flow, drop the redundant --method manual example (still interactive), extend the delete-command interactive notes to warn that the confirmation cannot be bypassed and deletion is irreversible, and restore the mapGroupBy polyfill helper for potential future use. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
vladfrangu
approved these changes
Apr 20, 2026
TC-MO
requested changes
Apr 20, 2026
Contributor
TC-MO
left a comment
TC-MO
left a comment
There was a problem hiding this comment.
- Grammar fixes: missing articles, wrong prepositions, subject-verb disagreement
- Tighter phrasing: trimmed wordiness on some descriptions
- … → ...: no benefit from the Unicode ellipsis in CLI terminal output
- Trailing periods: 9 flag/arg descriptions in files this PR already touches were missing them, added for consistency
Tech debt for follow-up: the new namespace descriptions use imperative voice ("Manage", "Log in", "Run") while existing descriptions use declarative ("Creates", "Prints", "Gets").
Both are fine individually, but mixed in the same --help menu it looks unintentional. Worth a pass to normalize everything to imperative (the gh/docker/kubectl convention), doesn't need to block this PR but should be done relatively soon.
Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Addresses PR feedback: no benefit from the Unicode ellipsis in CLI terminal output. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
Author
TC-MO
approved these changes
Apr 20, 2026
patrikbraborec
added a commit
that referenced
this pull request
Apr 22, 2026
Moves the inline example blocks out of the description and into the framework's `examples` field (added in #1080) so they render as the standard shell-comment EXAMPLES block, matching every other command. Also wires up `docsUrl` to surface the API reference in LEARN MORE. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
--helpoutput across all CLI commands with structured metadata (descriptions, examples, flags, environment variables) that is useful for both human users and AI agentsinteractiveNote,docsUrl,examples, andaiNotestatic properties to commands for richer help text_BaseCommandRenderer,CommandHelp,CommandWithSubcommands) to support the new structured output format#comments (matches theghCLI convention) in both per-command EXAMPLES and the main help menu, so each example is a self-contained copy-paste blockapify createexample to its interactive form with a#-commented description, instead of the misleadingapify create my-actorinvocationTest plan
yarn lintpassesyarn formatpasses (only untracked.claude/settings.local.jsonfails, not part of the project)yarn buildsucceedsapify <cmd> --helprenders example descriptions as#commentsapify helpmain menu shows the commentedapify createexampleCloses #1060
Help command before
Help command in this implementation